* @modifiers: modifier mask
*
* Determines whether a given keyval and modifier mask constitute
- * a valid keyboard accelerator. For example, the #GDK_KEY_a keyval
- * plus #GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator.
- * But, you can't, for instance, use the #GDK_KEY_Control_L keyval
- * as an accelerator.
+ * a valid keyboard accelerator.
+ *
+ * For example, the %GDK_KEY_a keyval plus %GDK_CONTROL_MASK mark is valid,
+ * and matches the “Ctrl+a” accelerator. But, you can't, for instance, use
+ * the %GDK_KEY_Control_L keyval as an accelerator.
*
* Returns: %TRUE if the accelerator is valid
*/
* @accelerator_mods: accelerator modifier mask
*
* Converts an accelerator keyval and modifier mask into a string
- * parseable by gtk_accelerator_parse(). For example, if you pass in
- * #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”.
+ * parseable by gtk_accelerator_parse().
+ *
+ * For example, if you pass in %GDK_KEY_q and %GDK_CONTROL_MASK,
+ * this function returns `<Control>q`.
*
* If you need to display accelerators in the user interface,
* see gtk_accelerator_get_label().
*
- * Returns: a newly-allocated accelerator name
+ * Returns: (transfer full): a newly-allocated accelerator name
*/
char *
gtk_accelerator_name (guint accelerator_key,
*
* GtkAccessible provides an interface for describing a UI element, like a
* #GtkWidget, in a way that can be consumed by Assistive Technologies, or
- * “AT”. Every accessible implementation has:
+ * “AT”.
+ *
+ * Every accessible implementation has:
*
* - a “role”, represented by a value of the #GtkAccessibleRole enumeration
* - an “attribute”, represented by a set of #GtkAccessibleState,
* @Title: GtkBuilder
*
* A GtkBuilder is an auxiliary object that reads textual descriptions
- * of a user interface and instantiates the described objects. To create
- * a GtkBuilder from a user interface description, call
+ * of a user interface and instantiates the described objects.
+ *
+ * To create a GtkBuilder from a user interface description, call
* gtk_builder_new_from_file(), gtk_builder_new_from_resource() or
* gtk_builder_new_from_string().
*
* g_cclosure_new_swap() for details.
*
* The list of flags that can be passed to gtk_builder_create_closure().
+ *
* New values may be added in the future for new features, so external
- * implementations of GtkBuilderScopeInterface should test the flags for unknown
- * values and raise a %GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error when they
- * encounter one.
+ * implementations of [interface@Gtk.BuilderScope] should test the flags
+ * for unknown values and raise a %GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error
+ * when they encounter one.
*/
typedef enum { /*< prefix=GTK_BUILDER_CLOSURE >*/
GTK_BUILDER_CLOSURE_SWAPPED = (1 << 0)
* @Title: GtkButton
*
* The #GtkButton widget is generally used to trigger a callback function that is
- * called when the button is pressed. The various signals and how to use them
- * are outlined below.
+ * called when the button is pressed.
*
* The #GtkButton widget can hold any valid child widget. That is, it can hold
* almost any other standard #GtkWidget. The most commonly used child is the
* @Title: GtkComboBox
* @See_also: #GtkComboBoxText, #GtkTreeModel, #GtkCellRenderer
*
- * A GtkComboBox is a widget that allows the user to choose from a list of
- * valid choices. The GtkComboBox displays the selected choice. When
- * activated, the GtkComboBox displays a popup which allows the user to
- * make a new choice. The style in which the selected value is displayed,
- * and the style of the popup is determined by the current theme. It may
- * be similar to a Windows-style combo box.
+ * A `GtkComboBox` is a widget that allows the user to choose from a list of
+ * valid choices. The `GtkComboBox` displays the selected choice; when
+ * activated, the `GtkComboBox` displays a popup which allows the user to
+ * make a new choice.
*
* The GtkComboBox uses the model-view pattern; the list of valid choices
* is specified in the form of a tree model, and the display of the choices
* simple alternative. Both GtkComboBox and #GtkComboBoxText can contain
* an entry.
*
- * # CSS nodes
+ * ## CSS nodes
*
* |[<!-- language="plain" -->
* combobox
* @Short_description: The description of a constraint
*
* `GtkConstraint` describes a constraint between an attribute on a widget
- * and another attribute on another widget, expressed as a linear equation
- * like:
+ * and another attribute on another widget, expressed as a linear equation.
+ *
+ * For instance:
*
* ```
* target.attr1 = source.attr2 × multiplier + constant
* @Short_description: Event controller to initiate DND operations
* @Title: GtkDragSource
*
- * GtkDragSource is an auxiliary object that is used to initiate
- * Drag-And-Drop operations. It can be set up with the necessary
+ * GtkDragSource is an event controller that is used to initiate
+ * Drag-And-Drop operations.
+ *
+ * GtkDragSource can be set up with the necessary
* ingredients for a DND operation ahead of time. This includes
* the source for the data that is being transferred, in the form
* of a #GdkContentProvider, the desired action, and the icon to
*
* A function which decides whether the row indicated by @iter matches
* a given @key, and should be displayed as a possible completion for @key.
+ *
* Note that @key is normalized and case-folded (see g_utf8_normalize()
* and g_utf8_casefold()). If this is not appropriate, match functions
* have access to the unmodified key via
* @See_also: #GtkGesture
*
* #GtkEventController is a base, low-level implementation for event
- * controllers. Those react to a series of #GdkEvents, and possibly trigger
- * actions as a consequence of those.
+ * controllers: ancillary object associated to widgets, which react
+ * to a series of #GdkEvents, and possibly trigger actions as a
+ * consequence.
*/
#include "config.h"
* @Title: GtkHeaderBar
* @See_also: #GtkBox, #GtkActionBar
*
+ * `GtkHeaderBar` is a widget for creating custom title bars for
+ * [class@Gtk.Window].
+ *
* GtkHeaderBar is similar to a horizontal #GtkBox. It allows children to
* be placed at the start or the end. In addition, it allows the window
* title to be displayed. The title will be centered with respect to the
* @Title: GtkIconTheme
*
* #GtkIconTheme provides a facility for looking up icons by name
- * and size. The main reason for using a name rather than simply
- * providing a filename is to allow different icons to be used
- * depending on what “icon theme” is selected
- * by the user. The operation of icon themes on Linux and Unix
+ * and size.
+ *
+ * The main reason for using a name rather than simply providing a filename
+ * is to allow different icons to be used depending on what “icon theme” is
+ * selected by the user. The operation of icon themes on Linux and Unix
* follows the [Icon Theme Specification](http://www.freedesktop.org/Standards/icon-theme-spec)
* There is a fallback icon theme, named `hicolor`, where applications
* should install their icons, but additional icon themes can be installed
* @GTK_IMAGE_GICON: the widget contains a #GIcon
* @GTK_IMAGE_PAINTABLE: the widget contains a #GdkPaintable
*
- * Describes the image data representation used by a #GtkImage. If you
- * want to get the image from the widget, you can only get the
- * currently-stored representation. e.g. if the
- * gtk_image_get_storage_type() returns #GTK_IMAGE_PAINTABLE, then you can
- * call gtk_image_get_paintable(). For empty images, you can request any
- * storage type (call any of the "get" functions), but they will all
- * return %NULL values.
+ * Describes the image data representation used by a [class@Gtk.Image].
+ *
+ * If you want to get the image from the widget, you can only get the
+ * currently-stored representation; for instance, if the gtk_image_get_storage_type()
+ * returns %GTK_IMAGE_PAINTABLE, then you can call gtk_image_get_paintable().
+ *
+ * For empty images, you can request any storage type (call any of the "get"
+ * functions), but they will all return %NULL values.
*/
typedef enum
{
*
* GtkLockButton is a widget that can be used in control panels or
* preference dialogs to allow users to obtain and revoke authorizations
- * needed to operate the controls. The required authorization is represented
- * by a #GPermission object. Concrete implementations of #GPermission may use
- * PolicyKit or some other authorization framework. To obtain a PolicyKit-based
- * #GPermission, use polkit_permission_new().
+ * needed to operate the controls.
+ *
+ * The required authorization is represented by a #GPermission object.
+ * Concrete implementations of #GPermission may use PolicyKit or some
+ * other authorization framework. To obtain a PolicyKit-based
+ * #GPermission, use `polkit_permission_new()`.
*
* If the user is not currently allowed to perform the action, but can obtain
* the permission, the widget looks like this:
#include <glib/gprintf.h>
/**
- * SECTION:filesystem
+ * SECTION:gtkmountoperation
* @short_description: Functions for working with GIO
* @Title: Filesystem utilities
*
+ * `GtkMountOperation` is an implementation of `GMountOperation` that
+ * can use a graphical user interface when requiring information from
+ * the user, like passwords or other information.
+ *
* The functions and objects described here make working with GTK and
* GIO more convenient.
*
* @Title: GtkPicture
* @SeeAlso: #GdkPaintable, #GtkImage
*
- * The #GtkPicture widget displays a #GdkPaintable. Many convenience functions
- * are provided to make pictures simple to use. For example, if you want to load
- * an image from a file, and then display that, there’s a convenience function
- * to do this:
- * |[<!-- language="C" -->
- * GtkWidget *widget;
- * widget = gtk_picture_new_for_filename ("myfile.png");
- * ]|
+ * The `GtkPicture` widget displays a `GdkPaintable`.
+ *
+ * Many convenience functions are provided to make pictures simple to use.
+ * For example, if you want to load an image from a file, and then display
+ * it, there’s a convenience function to do this:
+ *
+ * ```c
+ * GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png");
+ * ```
+ *
* If the file isn’t loaded successfully, the picture will contain a
* “broken image” icon similar to that used in many web browsers.
* If you want to handle errors in loading the file yourself,
* GtkPicture displays an image at its natural size. See #GtkImage if you want
* to display a fixed-size image, such as an icon.
*
- * # Sizing the paintable
+ * ## Sizing the paintable
*
* You can influence how the paintable is displayed inside the #GtkPicture.
* By turning off #GtkPicture:keep-aspect-ratio you can allow the paintable
* sure the paintable doesn't fill all available space but is instead displayed
* at its original size.
*
- * # CSS nodes
+ * ## CSS nodes
*
- * GtkPicture has a single CSS node with the name picture.
+ * `GtkPicture` has a single CSS node with the name `picture`.
*
- * # Accessibility
+ * ## Accessibility
*
- * GtkPicture uses the #GTK_ACCESSIBLE_ROLE_IMG role.
+ * `GtkPicture` uses the `GTK_ACCESSIBLE_ROLE_IMG` role.
*/
enum
* @Title: GtkTextBuffer
* @See_also: #GtkTextView, #GtkTextIter, #GtkTextMark
*
- * You may wish to begin by reading the
- * [text widget conceptual overview][TextWidget]
- * which gives an overview of all the objects and data
- * types related to the text widget and how they work together.
+ * Stores text (with or without attributes) for display in a
+ * [class@Gtk.TextView] widget.
+ *
+ * You may wish to begin by reading the [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and data types related to the
+ * text widget and how they work together.
*/
typedef struct _GtkTextLogAttrCache GtkTextLogAttrCache;
* @Short_description: Text buffer iterator
* @Title: GtkTextIter
*
+ * An iterator for the contents of a [class@Gtk.TextBuffer]
+ *
* You may wish to begin by reading the
* [text widget conceptual overview][TextWidget]
* which gives an overview of all the objects and data
* @Short_description: A position in the buffer preserved across buffer modifications
* @Title: GtkTextMark
*
+ * A position in a [class@Gtk.TextBuffer] preserved across modifications.
+ *
* You may wish to begin by reading the
* [text widget conceptual overview][TextWidget]
* which gives an overview of all the objects and data
* @Title: GtkTextTag
* @Short_description: A tag that can be applied to text in a GtkTextBuffer
*
+ * A tag that can be applied to text contained in a [class@Gtk.TextBuffer].
+ *
* You may wish to begin by reading the
* [text widget conceptual overview][TextWidget]
* which gives an overview of all the objects and
* @Short_description: Collection of tags that can be used together
* @Title: GtkTextTagTable
*
+ * The collection of tags in a [class@Gtk.TextBuffer].
+ *
* You may wish to begin by reading the
* [text widget conceptual overview][TextWidget]
* which gives an overview of all the objects and
* @Title: GtkTextView
* @See_also: #GtkTextBuffer, #GtkTextIter
*
+ * A widget that displays the contents of a [class@Gtk.TextBuffer].
+ *
* You may wish to begin by reading the
* [text widget conceptual overview][TextWidget]
* which gives an overview of all the objects and data
* types related to the text widget and how they work together.
*
- * # CSS nodes
+ * ## CSS nodes
*
* |[<!-- language="plain" -->
* textview.view
* If a context menu is opened, the window node will appear as a subnode
* of the main node.
*
- * # Accessibility
+ * ## Accessibility
*
* GtkTextView uses the #GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
*/
* @Short_description: Add tips to your widgets
* @Title: GtkTooltip
*
+ * An object representing a widget tooltip.
+ *
* Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text()
* or gtk_widget_set_tooltip_markup() without any explicit tooltip object.
*
* @data: (closure): user data
*
* A function used by gtk_tree_selection_set_select_function() to filter
- * whether or not a row may be selected. It is called whenever a row's
- * state might change. A return value of %TRUE indicates to @selection
- * that it is okay to change the selection.
+ * whether or not a row may be selected. It is called whenever a row's
+ * state might change.
+ *
+ * A return value of %TRUE indicates to @selection that it is okay to
+ * change the selection.
*
* Returns: %TRUE, if the selection state of the row can be toggled
*/
/**
* GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID:
*
- * The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a
- * #GtkTreeSortable use the default sort function.
+ * Uses the default sort function in a [interface@Gtk.TreeSortable].
*
- * See also gtk_tree_sortable_set_sort_column_id()
+ * See also: [method@Gtk.TreeSortable.set_sort_column_id]
*/
#define GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID (-1)
/**
* GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID:
*
- * The GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID can be used to make a
- * #GtkTreeSortable use no sorting.
+ * Disables sorting in a [interface@Gtk.TreeSortable].
*
- * See also gtk_tree_sortable_set_sort_column_id()
+ * See also: [method@Gtk.TreeSortable.set_sort_column_id]
*/
#define GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID (-2)
*
* A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive
* integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b
- * respectively. If two iters compare as equal, their order in the sorted model
+ * respectively.
+ *
+ * If two iters compare as equal, their order in the sorted model
* is undefined. In order to ensure that the #GtkTreeSortable behaves as
* expected, the GtkTreeIterCompareFunc must define a partial order on
* the model, i.e. it must be reflexive, antisymmetric and transitive.
* @data: (closure): user data
*
* A function to set the properties of a cell instead of just using the
- * straight mapping between the cell and the model. This is useful for
- * customizing the cell renderer. For example, a function might get an
- * integer from the @tree_model, and render it to the “text” attribute of
- * “cell” by converting it to its written equivalent. This is set by
- * calling gtk_tree_view_column_set_cell_data_func()
+ * straight mapping between the cell and the model.
+ *
+ * This function is useful for customizing the cell renderer. For example,
+ * a function might get an* integer from the @tree_model, and render it to
+ * the “text” attribute of “cell” by converting it to its written equivalent.
+ *
+ * See also: gtk_tree_view_column_set_cell_data_func()
*/
typedef void (* GtkTreeCellDataFunc) (GtkTreeViewColumn *tree_column,
GtkCellRenderer *cell,
* @width: the width of the widget’s allocated area.
* @height: the height of the widget’s allocated area.
*
- * A #GtkAllocation-struct of a widget represents region
- * which has been allocated to the widget by its parent. It is a subregion
- * of its parents allocation. See
- * [GtkWidget’s geometry management section][geometry-management] for
- * more information.
+ * The rectangle representing the area allocated for a widget by its parent.
*/
typedef GdkRectangle GtkAllocation;
projects / gtk4.git / commitdiff